Creating a Signal

A signal-definition consists of two types of properties; signal encoding properties and radio configuration properties. The first part specifies the characteristics of the data encoding of a signal whereas the radio part specifies the required radio configuration to receive the signal. This section discusses the signal encoding properties of the Homey Signal Definitions.

Example

The image below shows a repeating signal captured by a logic-analyzer from a KlikAanKlikUit remote. This signal will be used as an example throughout the article.

Legend

start-of-frame word 0 word 1 end-of-frame interval

The accompanying signal definition would therefore become:

/app.json

{
  "signals": {
    "433": {
      "klikaanklikuit": {
        "sof": [275, 2640], // Start of frame
        "eof": [275], // End of frame
        "words": [
          [250,  275, 250, 1250], // 0, or LOW
          [250, 1250, 250,  275], // 1, or HIGH
        ],
        "interval": 10000, // Time between two subsequent signal repetitions
        "sensitivity": 0.5, // between 0.0 and 0.5
        "repetitions": 20,
        "minimalLength": 32,
        "maximalLength": 36,
      }
    }
  }
}

Properties

The table below shows the minimum, maximum and default values of the encoding properties in the Homey signal definition.

Automatic Gain Control pulse (AGC)

The AGC attribute defines the synchronisation sequence of a signal in time-intervals. This part of the signal never changes and is used by most devices to properly configure the gain of the radio receiver, before the data arrives. The sequence is defined by an array of time-intervals in microseconds. The AGC pulse is ignored when receiving, but added in transmitted signals.

It is also possible to use Manchester encoding. In that case the agc-array has to be filled with 1's and 0's rather then using time-intervals. Each 1 is replaced by a ManchesterUnit high interval and each 0 is replaced by a ManchesterUnit low interval. This interval can be defined in the ManchesterUnit attribute.

Start-of-frame (SOF)

The start-of-frame attribute defines the preamble sequence of a signal in time-intervals. This part of the signal never changes and is used by most devices to detect an incoming signal. The sequence is defined by an array of time-intervals in microseconds

The start-of-frame definition in the example above starts with a high-state interval of 275 microseconds followed by a low-state interval of 2640 microseconds. The sof is shown in the signal image indicated in red.

When using Manchester encoding the word-array has to be filled with 1's and 0's rather then using time-intervals.

Words

The words attribute contains one or more words. Each word defines a sequence of high and low time-intervals depending on the type of encoding that is used. Most devices use single-level encoding where one word defines the 1 bit and the other word defines the 0 bit. In case of multi-level encoding the bitmask increases from one bit to multiple bits. Each bit combination (00, 11, 10, 01) then refers to a particular word.

In the above example, two words are defined. The 0 word indicated in yellow corresponds to a 0-bit. The 1 word indicated in green corresponds to a 1-bit. Therefore, the data that has been sent in the example will be 00111111010001010100110110010000 summing up to 32 bits. In the 'klik-aan-klik-uit' app these bits are futher split into multiple parts representing the homecode, unitcode and dim/onoff value.

When using Manchester encoding the word-array has to be filled with 1's and 0's rather then using time-intervals.

Data is sent and received using an array of binary (bit) values. Each bit (or bits when using multi-level encoding) refers to one of the words defined in the signal-definition. When sending data the array of bits gets converted to the corresponding words.

End-of-frame

The end-of-frame attribute defines the end-sequence of a signal. This part of the signal never changes. Make sure to specify minimalLengthWhen the EOF (partially) overlaps with the words, as this increases the amount of proper matches. When looking at the example, the end-of-frame consists of only one 275 microseconds interval. This is clearly shown in the signal-image indicated in blue.

When using Manchester encoding the eof-array has to be filled with 1's and 0's instead of a time-interval.

Interval

The interval attribute defines the time-interval between subsequent signals. The value is specified in microseconds.

ManchesterUnit

This time-interval is used when Manchester encoding is enabled. Instead of defining words in time-intervals, the developer has to define words in bits (1's and 0's). A word like [1, 0] with a Manchester unit time-interval of 100 microseconds gets encoded into a high signal of 100 microseconds and a low signal of 100 microseconds.

MinimalLength

The minimalLength attribute defines the minimal length of a signal in words. Sometimes devices use varying signal lengths depending on the size of the payload.

MaximalLength

The maximalLength attribute defines the maximal length of a signal in words. Some devices use varying signal lengths depending on the size of the payload.

PrefixData

The PrefixData attribute can be used to specify words that have to be added in front of each payload before transmission. When specified, incoming payloads are checked for these prefix-words, and only upon a match, the words will be stripped and the payload without prefix will be delivered to the Homey app. The words are prepended to each payload before transmitting as well.

PostfixData

The PostfixData attribute can be used to specify words that have to be appended after each payload before transmission. When specified, incoming payloads are checked for these postfix-words, and only upon a match, the words will be stripped and the payload without postfix will be delivered to the Homey app. The words are also appended to each payload before transmitting as well.

Commands

Sometimes, devices have a static set of commands and do not include any dynamic data such as an address. This is the case for most infrared devices. In these cases, the cmds attribute can be used to predefine all commands. This property consists of an object that maps commands (specified as identifier string) to an actual payload array (excluding prefix/postfix data).

Toggle SOF

Some signals use toggle bits. These toggle bits are used to differentiate between multiple key presses of the same command or button, by flipping the bits upon each new transmission. Homey-Signals contain two different ways to specify this behaviour.

The toggleSOF property can be used to specify a custom SOF that is being alternated with the primary SOF. This works automatically for both receiving and sending, and adjusts the first argument of both the cmd and payload events.

Toggle Bits

Some signals use toggle bits. These toggle bits are used to differentiate between multiple key presses of the same command or button, by flipping the bits upon each new transmission. Homey-Signals contain two different ways to specify this behaviour.

The toggleBits property can be used to specify bit indexes of these toggle bits inside the payload (including prefix/postfix). This works automatically for both receiving and sending, and adjusts the first argument of both the cmd and payload events. Note: The reported payload contains unmodified data, with the toggle bits as transmitted.

Sensitivity

The sensitivity attribute defines the maximum deviation between the signal-definition and the received signal. This value represents the maximal percentage signals may deviate of the definition.

Packing

When sending or receiving large amounts of data it may be more convenient to receive the data in bytes rather then bits. Enabling packing makes it possible to send and receive byte- rather then bit-arrays. Every eight bits are 'packed' into a byte and added to the byte-array. Usage of this property is discouraged when the payload length is not a multiple of eight, and impossible when the signal does not contain exactly two words.

txOnly

The txOnly attribute can be used to disable the receiving subsystem of the signal, proper usage is encouraged in order to save computing resources.